home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 July / EnigmA AMIGA RUN 09 (1996)(G.R. Edizioni)(IT)[!][issue 1996-07 & 08][EARSAN CD VIII].iso / earcd / dev1 / explrr16.rdm < prev    next >
Text File  |  1996-06-17  |  8KB  |  177 lines
  1. Short:  Amazing System Browser and Debugger
  2. Author: jason@fsel.com (Jason R. Hulance)
  3. Type:   dev/e
  4.  
  5. Explorer 1.6j
  6. =============
  7. Allows you to browse around memory as E objects (which are like C structs).
  8. (Minor update to 1.5j, a small bug-fix for v37/8 compatibility.)
  9.  
  10. Basic Function
  11. --------------
  12. You enter an address and then select the object which is (supposed to be?)
  13. at that address.  You can then see the value that each element of the
  14. object takes, and follow pointers etc. by double-clicking on the element (a
  15. single click changes the address to the element's address, which is an
  16. offset from the address you specified for the object).
  17.  
  18. A double-click may therefore change the object being browsed, so there is a
  19. way of returning to the original object via the "Back Up" button.  As you
  20. double-click and select new objects your choices are recorded.  The current
  21. depth of this path is shown as the 'Depth:' text.  The action of the
  22. "Back Up" button is duplicated by the "Back Up" menu item on the
  23. "Selections" menu.  There is also an option to clear the current path on
  24. this menu.
  25.  
  26. The list of objects may be created in several ways (these are found on the
  27. "Project" menu):
  28.  
  29.  1) "Load."   Scan the selected module or all the modules in the selected
  30.               directory and its sub-directories.  The found objects will
  31.               replace any current list of objects.
  32.  2) "Merge."  Same as 1) but any objects found are added to the current
  33.               list of objects rather than replacing them.
  34.  3) "Load Cache."  Same as 1) but the current E module cache is scanned.
  35.                    This is most useful when Explorer is used to help debug
  36.                    your programs.
  37.  
  38. The address and object can also be specified via ARexx, making Explorer an
  39. extremely useful debugging tool as well as a system browser!  (A module is
  40. supplied to show how easy it is to integrate the appropriate ARexx call
  41. into your program.)
  42.  
  43. Object Layout
  44. -------------
  45. The elements of the selected object are listed in order.  If you choose to
  46. see the value of element it will be displayed in hex in parenthesis after
  47. the element, and if you choose to see the element address (an offset from
  48. the object address) it will be displayed after an '@'.  (Use the
  49. "Selections" menu to decide which, if any, you want to see.)
  50.  
  51. Where to Start
  52. --------------
  53. Explorer starts off with the address of an internal hail and copyright
  54. string.  The items on the "Presets" menu give some other, interesting
  55. starting points:
  56.  
  57.  1) "Dos."   Views the address stored in the 'dosbase' global variable as
  58.              a 'doslibrary' object.  The dos.library is one of the
  59.              fundamental Amiga system libraries, and 'dosbase' is its
  60.              corresponding library base object.
  61.  2) "Exec."  Same as 1) but for the 'execbase' variable and object for the
  62.              exec.library (the most fundamental Amiga system library).
  63.  3) "Graphics."   Same as 1) but for the 'gfxbase' variable and object for
  64.                   the graphics.library.
  65.  4) "Intuition."  Same as 1) but for the 'intuitionbase' variable and
  66.                   object for the intuition.library.
  67.  5) "This Process."  Views the 'process' object for the running Explorer
  68.                      program!
  69.  
  70. For a typical Explorer session, you would probably start at one of these
  71. points and then double-click on elements and use the "Back Up" button to
  72. browse around.  You never really need to set the address explicitly on the
  73. GUI (at worst you'd do it by ARexx), but the option is there if you really
  74. want to...
  75.  
  76. Simple Types
  77. ------------
  78. The "CHAR", "INT" and "LONG" buttons view the contents of the address as if
  79. it were a pointer to the corresponding type, and fills in the 'Hex:',
  80. 'Decimal:' and 'String:' texts with the value(s) being pointed at.
  81.  
  82. "BSTR" is similar to "CHAR" but it first converts the address from a BCPL
  83. pointer and then skips over the length byte.  "BADDR" just converts the
  84. address to a BCPL pointer.
  85.  
  86. "--" and "++" treat the address as if it were pointing to an array of the
  87. type last requested (i.e., an object or simple type).  "--" moves the
  88. address back to the previous element in the array, and "++" moves it on to
  89. the next.  The size of the last requested type is shown as the 'Size:'
  90. text.
  91.  
  92. Display Beeps!
  93. --------------
  94. The screen will flash (or you'll get a beep or whatever your Workbench is
  95. set up to do) if you do one of the following:
  96.  
  97.  1) Select something when the address is NIL (zero).  A NIL address is not
  98.     valid (although Explorer will behave as if it were).
  99.  2) Select an element which is a NIL pointer or a LONG that is NIL.
  100.  3) Select an element with object or PTR TO object type, where the object
  101.     is not in the current list of objects.
  102.  4) Backup past a depth of zero.
  103.  
  104. Command Line Options
  105. --------------------
  106. The command line template is 'OBJECT,ADDR,ALL/S,CACHE/S,NONE/S'.
  107.  
  108.  1) 'OBJECT'  Specify an initial object to be displayed (to be useful, the
  109.               appropriate module must also be loaded using 'ALL' or
  110.               'CACHE').
  111.  2) 'ADDR'    Specify an initial address to be displayed (NIL is ignored!).
  112.  3) 'ALL'     Load all objects from the modules in Emodules: and its
  113.               sub-directories.
  114.  4) 'CACHE'   Load all objects from the modules in the current E module
  115.               cache.
  116.  5) 'NONE'    Start with no objects (overrides 'ALL' and 'CACHE').
  117.  
  118. By default, no objects will be loaded and the starting address will be that
  119. of an internal hail and copyright string (which will be displayed as the
  120. 'String:' text).
  121.  
  122. ARexx
  123. -----
  124. The "Reply" menu item on the "ARexx" menu manually replies to an ARexx
  125. message that may have been received.  You can also let Explorer
  126. automatically reply to these messages by checking the "Auto Reply" option,
  127. but the manual method is best since you can be sure that the pointers
  128. remain valid while you browse (since the calling program is halted).  Once
  129. you've replied to a message the calling program is free to scribble all
  130. over the memory at the address it just gave you...
  131.  
  132. A module 'sendexplorer' is supplied to simplify the debugging facilities of
  133. Explorer.  It defines a single function, 'sendExplorer', which you call
  134. with the address and object name you are interested in.  The third,
  135. optional parameter is a message port for replies.  If you don't supply this
  136. then a temporary port is created for the duration of the function call.
  137. (The purpose of this parameter is to allow you to re-use the same port
  138. during your program if you call 'sendExplorer' a lot.)  An example call is:
  139.  
  140.   sendExplorer(packet, 'dospacket')
  141.  
  142. To browse using your own objects you'd separate them out into modules and
  143. load these modules in your program.  Compiling your program would add these
  144. to the E module cache, which can then be used to set-up Explorer (using the
  145. "Load Cache" menu item).  Alternatively, you could "Load" or "Merge" the
  146. appropriate module directly.
  147.  
  148. Example Program
  149. ---------------
  150.  
  151. To show how useful Explorer can be, there is a modified version of the
  152. 'empty' handler supplied.  This uses the above call to 'sendExplorer' to
  153. communicate the value of the packet currently being processed.  Since the
  154. handler is not a full process (it's just a task) there would normally be no
  155. simple way of debugging it or examining the packets as they arrive (none of
  156. the DOS functions, such as printing text, are available to simple tasks).
  157. However, the handler can send messages to ARexx and thus to Explorer.
  158.  
  159. To try it out:
  160.  
  161.  1) Make sure ARexx is up (by running RexxMast, if necessary).
  162.  2) Start up Explorer using,
  163.       run explorer all
  164.  3) Now copy the 'empty-handler' to L:,
  165.       copy empty-handler L:
  166.  4) Mount it using,
  167.       mount empty: from empty.mountlist
  168.  5) Use the handler,
  169.       type empty:10
  170.  6) Look at Explorer.  It will be displaying the first packet.  Browse
  171.     around it, remembering that most elements will be BCPL strings.
  172.  7) Select "Reply" from the ARexx menu (or press RAmiga-R) to reply to this
  173.     message.
  174.  8) Another packet arrives and the message is sent to Explorer.
  175.  9) Repeat 6)-8) until the 'type' command finishes and you get the Shell
  176.     prompt back.
  177.